---
title: Configuration
description: How configure Unistyles
---

import { Card, CardGrid, Aside, Tabs, TabItem } from '@astrojs/starlight/components'
import Seo from '../../../../components/Seo.astro'

<Seo
    seo={{
        title: 'Configure Unistyles',
        description: 'Learn how to configure Unistyles'
    }}
>

To unlock more features and tailor Unistyles to your needs, you can configure it. The Unistyles configuration is divided into three parts:

1. **Themes**
2. **Breakpoints**
3. **Settings**

<Aside>
Each configuration is optional but enables advanced features, which are explained in the guide [How Unistyles Works?](/v3/start/how-unistyles-works)
</Aside>

### Themes (Optional)

`Themes` is a JavaScript object where the keys represent unique theme names, and the values are the corresponding theme definitions. For more details, refer to the [theming](/v3/guides/theming) guide.

```tsx title="unistyles.ts"
const lightTheme = {
    colors: {
        primary: '#ff1ff4',
        secondary: '#1ff4ff'
        // any nesting, spreading, arrays, etc.
    },
    // functions, external imports, etc.
    gap: (v: number) => v * 8
}

const otherTheme = {
    colors: {
        primary: '#aa12ff',
        secondary: 'pink'
    },
    gap: (v: number) => v * 8
}

const appThemes = {
    light: lightTheme,
    other: otherTheme
}
```

<Aside>
Unistyles supports any dynamic theme and doesn’t enforce a specific structure. To avoid TypeScript issues, ensure that all themes share the same type.
</Aside>

### Breakpoints (Optional)

`Breakpoints` is a JavaScript object where the keys are unique breakpoint names and the values are the corresponding breakpoint values (numbers). Be sure to register at least one breakpoint with a value of 0, as it’s required to simulate the cascading behavior of CSS media queries.

```tsx title="unistyles.ts"
const breakpoints = {
    xs: 0, // <-- make sure to register one breakpoint with value 0
    sm: 300,
    md: 500,
    lg: 800,
    xl: 1200
    // use as many breakpoints as you need
}
```

### Settings (Optional)

The `Settings` object has been simplified, and in the most recent version, it supports only four properties:

- **`adaptiveThemes`** – a boolean that enables or disables adaptive themes [learn more](/v3/guides/theming#adaptive-themes)
- **`initialTheme`** – a string or a synchronous function that sets the initial theme
- **`CSSVars`** – a boolean that enables or disables web CSS variables (defaults to `true`) [learn more](/v3/references/web-only#css-variables)
- **`nativeBreakpointsMode`** - iOS/Android only. User preferred mode for breakpoints. Can be either `points` or `pixels` (defaults to `pixels`) [learn more](/v3/references/breakpoints#pixelpoint-mode-for-native-breakpoints)

```tsx title="unistyles.ts"
const settings = {
    initialTheme: 'light'
}

// or with a synchronous function
const settings = {
    initialTheme: () => {
        // get preferred theme from user's preferences/MMKV/SQL/StanJS etc.

        return storage.getString('preferredTheme') ?? 'light'
    }
}

// or with adaptive themes
const settings = {
    adaptiveThemes: true
}
```

<Aside>
In the Unistyles 3.0 setting both `initialTheme` and `adaptiveThemes` will cause an error. These options are mutually exclusive.
</Aside>

### TypeScript Types (Optional)

If your repository is using TypeScript, it is highly recommended to override the library types for optimal autocomplete and type safety regarding your themes and breakpoints:

```tsx title="unistyles.ts"
type AppThemes = typeof appThemes
type AppBreakpoints = typeof breakpoints

declare module 'react-native-unistyles' {
    export interface UnistylesThemes extends AppThemes {}
    export interface UnistylesBreakpoints extends AppBreakpoints {}
}

```

### Set configuration

The final step in the configuration is to set all the options by calling the `StyleSheet.configure` function:

```tsx title="unistyles.ts"
import { StyleSheet } from 'react-native-unistyles'

StyleSheet.configure({
    themes: appThemes,
    breakpoints,
    settings
})

```

That’s it! You can now use all the features of Unistyles in your project!

<Aside>
Don't forget to import this config somewhere in your project, for example in `index.ts` file.
You **must** call `StyleSheet.configure` **before** any `StyleSheet.create` call.

For expo router users, please refer to the [Expo Router guide](/v3/guides/expo-router).
</Aside>

### Full example

```tsx title="unistyles.ts"
import { StyleSheet } from 'react-native-unistyles'

const lightTheme = {
    colors: {
        primary: '#ff1ff4',
        secondary: '#1ff4ff'
    },
    gap: (v: number) => v * 8
}

const otherTheme = {
    colors: {
        primary: '#aa12ff',
        secondary: 'pink'
    },
    gap: (v: number) => v * 8
}

const appThemes = {
    light: lightTheme,
    other: otherTheme
}

const breakpoints = {
    xs: 0,
    sm: 300,
    md: 500,
    lg: 800,
    xl: 1200
}

type AppBreakpoints = typeof breakpoints
type AppThemes = typeof appThemes

declare module 'react-native-unistyles' {
    export interface UnistylesThemes extends AppThemes {}
    export interface UnistylesBreakpoints extends AppBreakpoints {}
}

StyleSheet.configure({
    settings: {
        initialTheme: 'light',
    },
    breakpoints,
    themes: appThemes
})

```

</Seo>
